feat(billing): charge and report Stripe service fees

[jeanduplessis]

Summary

Adds the complete Stripe service-fee implementation for eligible credit top-ups and Kilo Pass purchases, with durable fee assessments, trusted product-principal settlement, exemptions, lifecycle adjustments, fee-only reporting, and rollout audits.

Why this change is needed

A 5% Stripe line item alone is not enough to operate the fee safely. The platform must distinguish product principal from the added fee so credits, entitlements, affiliate value, and product analytics do not use gross payment amounts. It must also retain fee decisions when no line is charged, survive Stripe webhook ordering and retries, handle refunds and disputes, support reasoned organization exemptions, and report collected or missed fees without turning the sidecar into a second payment ledger.

This PR replaces the six-PR stack in #5236, #5262, #5263, #5264, #5265, and #5266 so the complete behavior can be reviewed and merged as one unit.

How this is addressed

• Add an additive two-table schema: one service-fee assessment per commercial event and an append-only organization exemption history.
• Calculate and attach a separate 5% fee line to eligible personal and organization top-ups and Kilo Pass purchases, including recurring and automatic invoice flows.
• Keep product settlement independent from gross Stripe amounts so service fees never increase credits, entitlements, affiliate commission, or product analytics.
• Fail open when a positive fee cannot be prepared or attached while retaining a durable missed-fee assessment for audit and reporting.
• Enrich one assessment across Checkout, Invoice, PaymentIntent, Charge, refund, and dispute events with idempotent, order-tolerant state transitions.
• Allocate fee refunds proportionally and track reversible fee disputes without persisting disputed product principal.
• Add exact-organization exemption controls with immutable reasons and historical decision references.
• Preserve the existing credit_transactions revenue series and report assessment-backed fee metrics separately by UTC settlement date, including collected, missed, exempted, and disputed amounts.
• Add read-only Kilo Pass classification and restricted-coupon audits for rollout safety.

Human Verification

• Compared the final implementation requirement by requirement with .plans/service-fees/PRAGMATIC-SIDECAR.md and confirmed the fee sidecar does not become a product or payment ledger.
• Verified the legacy paid, free, multiplied, and unmultiplied credit-revenue SQL remains unchanged from its pre-service-fee baseline; fee reporting is additive.
• Applied all migrations successfully to an empty PostgreSQL database.
• Passed 161 focused revenue, service-fee, persistence, dispute, and admin-dashboard tests.
• Passed 1,118 broader Stripe, Kilo Pass, credits, organization, affiliate, and email tests, with 2 skipped.
• Exercised /admin/revenue with fake local data: assessment-backed credits remained in Paid Revenue, Kilo Pass produced a fee-only UTC day, refund/dispute overlap clamped collected fees to zero, empty ranges rendered correctly, and CSV output used the narrowed fee-only shape.

Reviewer Notes

Human Reviewer Flags

• The assessment table is intentionally a narrow fee-decision sidecar. Stripe remains authoritative for charges, invoices, refunds, and disputes, while credit_transactions remains authoritative for the existing product-revenue series.
• Positive fee failures fail open: the underlying purchase proceeds and the missed expected fee remains auditable. No later corrective charge is created automatically.
• Hosted Checkout discounts may reduce the settled fee below the prepared fee. Expected and charged fee amounts therefore remain separate.
• Organization exemptions are exact-organization, non-inherited, append-only, and internal; they are not exposed through customer-facing audit logs.
• Kilo Pass contributes service-fee metrics only. This change does not add Kilo Pass product revenue or claim authoritative gross revenue in the admin dashboard.
• A human-driven Stripe test-mode dispute lifecycle remains a release validation step because Stripe CLI cannot attach a dispute to an existing charge.

Code Reviewer Agent

Code Reviewer Notes

• Review the trusted-principal boundary before route wiring: product value comes from classified product lines and metadata, never from gross paid minus an assumed fee.
• Checkout, Kilo-owned auto-top-up invoices, and Stripe-advanced Kilo Pass invoices have distinct attachment ownership to prevent duplicate fee lines.
• Unique Stripe-object indexes and transactional assessment updates make webhook retries idempotent while permitting out-of-order enrichment.
• Refund allocation is cumulative to avoid partial-refund rounding drift. Collected fee reporting clamps each assessment with GREATEST(charged - refunded - disputed, 0) before aggregation.
• Fee reporting is gated by settled_at and grouped in UTC. Assessment rows are never anti-joined out of the existing credit-revenue query.
• Migration 0221 is additive and unshipped: it creates only the assessment and exemption tables, with generated snapshot metadata.

[IamCoder18]

Are no Stripe fees being charged until November? The email said "September 1". If so, this would be great!