docs: update README and improve zap handling in webhooks and services

- Added a production checklist for Zaps (Lightning) in README.md, detailing necessary steps for historic zap visibility.
- Enhanced comments in webhooks.service.ts to clarify zap handling and webhook requirements for BTCPay Server.
- Improved logging in zaps.service.ts to provide more detailed information on zap payouts and recorded stats.
- Updated error handling in zaps.service.ts to ensure robust logging if zap stats recording fails.
- Refined getZapStats method in indeehub-api.service.ts to clarify mock data usage in development.

These changes improve documentation and enhance the handling of zap-related functionalities across the application.

backend/README.md

@@ -223,6 +223,18 @@ npm run build # after you finish the migrations
 npm run typeorm:run-migrations # will apply the migrations to the current DB
 ```
 
+# Zaps (Lightning) – production checklist
+
+For historic zaps to show on film cards and in the movie modal:
+
+1. **Migrations** – The `zap_stats` table is created by migration `1762000000000-add-zap-stats`. The Dockerfile runs migrations on startup; if you deploy without Docker, run `npm run typeorm:run-migrations` once.
+
+2. **BTCPay webhook** – In BTCPay Server: Store → Webhooks → Add webhook. Set the URL to `https://your-domain/api/webhooks/btcpay` (or `/api/webhooks/btcpay-webhook`). Subscribe to **Invoice settled**. Without this, zap payments are not recorded.
+
+3. **Backend logs** – After a zap is paid you should see: `Zap payout completed: <invoiceId> — stats recorded for project <projectId>` and `Zap stats saved: project <id> total N zaps, M sats`. If you see `Failed to record zap stats`, check that the `zap_stats` table exists.
+
+4. **API** – `GET /zaps/stats?projectIds=id1,id2` must be reachable (e.g. `https://your-domain/api/zaps/stats?projectIds=...`). It is not cached and does not require auth.
+
 &nbsp;
 
 # Running Stripe Webhooks locally