Add promotional mail classification and volume-backed OCR image staging

[thejonathangu]

Summary

Adds a FEATURE_PROMO_CLASSIFICATION flag and an isPromotional field on MAIL so admins can mark mail as promotional during single-entry capture and bulk OCR review.

Note for reviewers: an earlier draft of this PR was stacked on top of feat/ocr-image-staging, which has since been merged via #118. The diff against main is now scoped to the promo-classification work only (4 commits + a single new env line in docker-compose-prod.yml for the new flag).

Changes

• Backend: isPromotional plumbed through models/builders.py, ocr_queue_repository.py, and ocr_queue_controller.py. New FEATURE_PROMO_CLASSIFICATION flag in config.py, .env.sample, and both compose files.
• Frontend: Toggle exposed in OcrQueue.tsx and RecordEntry.tsx, wired through mail.ts / ocrQueue.ts, and added to the feature-flags hydration in App.tsx (also fixes a bug where the full flags payload wasn't being copied into the store).
• Docs: Data-model diagram + architecture doc updated; design plan in docs/02-plans/plan-promotional-mail-classification-toggle.md.
• Tests: test_mail_service_create.py, test_models.py, mail-api.test.ts cover the new field. New PromoClassificationGatingTests in test_ocr_queue_controller.py confirms isPromotional is dropped from PATCH writes and from the MAIL payload at confirm time when the flag is off.

Intentional design notes

• Queue rows store isPromotional: False explicitly; MAIL docs omit False. The review UI reads queue rows directly and benefits from the field always being present (lets the toggle render without an extra null check). MAIL is the source of truth for downstream consumers and stays sparse — build_mail_create only writes isPromotional when it's True. There's now a comment on create_ocr_queue_items calling this out.
• Soft-delete filtering (raised by reviewer): get_ocr_queue_items_for_job already filters status: "deleted" rows out via {"status": {"$ne": "deleted"}}, so the admin queue view never surfaces pruned items. That code lives on main (came in via Feat/ocr image staging #118).

Test plan

• cd backend && python -m unittest tests.unit.test_mail_service_create tests.unit.test_models tests.unit.test_ocr_queue_controller
• cd frontend && npm test -- mail-api
• Toggle FEATURE_PROMO_CLASSIFICATION=true, mark a piece as promotional in both RecordEntry and the OCR review screen, confirm it persists on the resulting MAIL doc.
• Toggle off, confirm the UI hides the control, the PATCH endpoint silently drops any isPromotional value, and confirm() does not write isPromotional to MAIL even if a stale queue row carries it.

Closes #90

[gekiclaws]

Nice work! The promo classification flow itself looks clean, and feature-gating it makes sense.

Main concern is that this PR is doing more than the title suggests. It includes promo classification, OCR auto-extract gating, volume-backed image storage, image pruning, scheduler config, and a CI timeout change. I’d rename it to something like Add promotional mail classification and volume-backed OCR image staging, or split the image-staging/pruning pieces out if that is still easy.

A few things to check before merge:

• Replace/remove the #<ocr-image-staging-pr> placeholder in the PR body.
• Add/confirm tests for isPromotional being ignored when FEATURE_PROMO_CLASSIFICATION=false.
• Confirm status: "deleted" OCR queue rows are filtered out in the admin queue after pruning.
• Add the image upload/load/prune path to the test plan, since that is a substantial part of this diff.
• Decide whether the queue should persist isPromotional: false while MAIL omits false values. That may be fine, but it should be intentional.

[gekiclaws]

REDACTED