docs: promo-code contract

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ByAwHU4pRnyE58YocQvAas

README.md

@@ -62,6 +62,13 @@ Events includes a shareable ticket scanner, which can be used to register attend
 - **Stripe session.** The buyer's email is passed as `customer_email`
   (prefilled and locked on the hosted page); the line item is named after the
   event; `event_id`, `quantity` and `ticket_ids` ride along as metadata.
+- **Promo codes.** `extra.promo_codes` (`code`, `discount_percent`, `active`,
+  `max_uses`; `used_count` is derived from paid tickets) are organizer-only: they are
+  never part of public responses. Buyers preview a code with
+  `POST /events/api/v1/promo/validate/{event_id}` (`{codes, quantity}` → v2-shaped
+  `BasketTotals` + `currency`); purchase enforces `active` and `max_uses` (each ticket
+  of a multi-ticket purchase consumes one use) and rejects bad codes with a distinct
+  `detail`. Updates that omit `extra.promo_codes` keep the stored list.
 - **Email.** Multipart text + HTML (links, no images) with the **ticket card**
   attached — a self-describing PNG (site, event, when, where, QR with the
   instance logo, name on ticket, ticket id) also served at