docs: update subscription feature documentation - M7 (refs #55)

frontend/src/features/subscription/README.md

@@ -4,20 +4,21 @@ Frontend UI for subscription management with Stripe integration.
 
 ## Overview
 
-Provides subscription tier management, payment method updates, and billing history viewing.
+Provides subscription tier management, payment method updates, billing history, donations, and vehicle selection during downgrade flow.
 
 ## Components
 
 ### TierCard
-Displays subscription plan with:
-- Plan name and pricing (monthly/yearly)
+Subscription plan display with:
+- Plan name and pricing (monthly/yearly toggle)
 - Feature list
 - Current plan indicator
 - Upgrade/downgrade button
 
 ### PaymentMethodForm
 Stripe Elements integration for:
-- Credit card input with validation
+- Credit card input with CardElement
+- Real-time validation
 - Payment method creation
 - Error handling
 
@@ -27,85 +28,130 @@ Invoice list with:
 - PDF download links
 - MUI Table component
 
+### VehicleSelectionDialog
+Vehicle selection during downgrade:
+- Checkbox list for each vehicle
+- Counter showing selected vs allowed
+- Warning about tier-gated vehicles
+- Validation preventing over-selection
+
+### DowngradeFlow
+Orchestrates downgrade process:
+- Checks vehicle count vs target tier limit
+- Shows VehicleSelectionDialog if needed
+- Submits vehicle selections to backend
+
+### DonationSection / DonationSectionMobile
+One-time donation form:
+- Free-form amount input (no presets)
+- $0.50 minimum (Stripe limit)
+- Stripe CardElement for payment
+- Donation history table
+- Success feedback
+
 ## Pages
 
 ### SubscriptionPage (Desktop)
-- Current plan card with status
-- Three-column tier cards layout
-- Payment method section
+MUI-based layout:
+- Current plan card with status badges
+- Three-column tier comparison
+- Monthly/yearly toggle
+- Payment method modal
 - Billing history table
-- Material-UI components
+- Donation section
 
 ### SubscriptionMobileScreen (Mobile)
+Tailwind-based layout:
+- GlassCard styling
 - Stacked card layout
 - Touch-friendly buttons (44px min)
-- Tailwind styling
-- GlassCard components
+- Modal payment forms
 
 ## API Integration
 
-All endpoints are in `/subscriptions`:
-- GET `/subscriptions` - Current subscription
-- POST `/subscriptions/checkout` - Upgrade subscription
-- POST `/subscriptions/cancel` - Cancel subscription
-- POST `/subscriptions/reactivate` - Reactivate subscription
-- PUT `/subscriptions/payment-method` - Update payment method
-- GET `/subscriptions/invoices` - Invoice history
+### Subscriptions
+| Endpoint | Method | Hook |
+|----------|--------|------|
+| /api/subscriptions | GET | useSubscription() |
+| /api/subscriptions/checkout | POST | useCheckout() |
+| /api/subscriptions/cancel | POST | useCancelSubscription() |
+| /api/subscriptions/reactivate | POST | useReactivateSubscription() |
+| /api/subscriptions/downgrade | POST | useDowngrade() |
+| /api/subscriptions/payment-method | PUT | useUpdatePaymentMethod() |
+| /api/subscriptions/invoices | GET | useInvoices() |
+
+### Donations
+| Endpoint | Method | Hook |
+|----------|--------|------|
+| /api/donations | POST | useCreateDonation() |
+| /api/donations | GET | useDonations() |
 
 ## Hooks
 
-- `useSubscription()` - Fetch current subscription
-- `useCheckout()` - Upgrade subscription
-- `useCancelSubscription()` - Cancel subscription
-- `useReactivateSubscription()` - Reactivate subscription
-- `useInvoices()` - Fetch invoice history
+| Hook | Purpose |
+|------|---------|
+| useSubscription() | Fetch current subscription |
+| useCheckout() | Upgrade subscription |
+| useCancelSubscription() | Cancel subscription |
+| useReactivateSubscription() | Reactivate subscription |
+| useDowngrade() | Downgrade with vehicle selection |
+| useInvoices() | Fetch billing history |
+| useCreateDonation() | Create donation payment |
+| useDonations() | Fetch donation history |
 
-## Environment Setup
+## Environment Variables
 
-Required environment variable:
 ```bash
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
 ```
 
 ## Subscription Tiers
 
-### Free
+### Free ($0)
 - 2 vehicles
 - Basic tracking
 - Standard reports
-- Price: $0
 
-### Pro
+### Pro ($1.99/month or $19.99/year)
 - Up to 5 vehicles
 - VIN decoding
 - OCR functionality
 - API access
-- Price: $1.99/month or $19.99/year
 
-### Enterprise
+### Enterprise ($4.99/month or $49.99/year)
 - Unlimited vehicles
 - All Pro features
 - Priority support
-- Price: $4.99/month or $49.99/year
 
-## Mobile Navigation
+## Routing
 
-Add subscription screen to settings navigation:
-```typescript
-navigateToScreen('Subscription')
-```
+- Desktop: `/garage/settings/subscription`
+- Mobile: `navigateToScreen('Subscription')`
 
-## Desktop Routing
+## Files
 
-Route: `/garage/settings/subscription`
+| File | Purpose |
+|------|---------|
+| types/subscription.types.ts | TypeScript interfaces |
+| api/subscription.api.ts | API client calls |
+| hooks/useSubscription.ts | React Query hooks |
+| constants/plans.ts | Tier configuration |
+| components/TierCard.tsx | Plan display card |
+| components/PaymentMethodForm.tsx | Stripe Elements form |
+| components/BillingHistory.tsx | Invoice table |
+| components/VehicleSelectionDialog.tsx | Vehicle selection modal |
+| components/DowngradeFlow.tsx | Downgrade orchestrator |
+| components/DonationSection.tsx | Desktop donation UI |
+| components/DonationSectionMobile.tsx | Mobile donation UI |
+| pages/SubscriptionPage.tsx | Desktop page |
+| mobile/SubscriptionMobileScreen.tsx | Mobile screen |
 
 ## Testing
 
-Test subscription flow:
 1. View current plan
 2. Toggle monthly/yearly billing
-3. Select upgrade tier
-4. Enter payment method
-5. Complete checkout
-6. Verify subscription update
-7. View billing history
+3. Upgrade: Select tier, enter payment, complete checkout
+4. Downgrade: Select vehicles to keep if over limit
+5. Cancel/reactivate subscription
+6. Make a donation
+7. View billing and donation history