feat: Implement loyalty and wholesale services with models, routes, and validation

- Added models for loyalty points allocation, redemption, rewards, tiers, tier history, and referrals.
- Created business credit ledger entries, settlements, and settlement items models.
- Developed services for loyalty operations including account management, point allocation, redemption, and referral handling.
- Implemented wholesale credit management services for transactions and settlements.
- Established routes for loyalty and wholesale admin and customer operations with appropriate middleware for authentication and permission checks.
- Introduced validation schemas for loyalty and wholesale operations.
- Set up cron jobs for loyalty reconciliation tasks such as birthday rewards and point expirations.
- Created migration scripts to set up the database schema for loyalty and wholesale features.
- Added unit tests for validation and policy enforcement in loyalty and wholesale services.

Documentation/API_LOYALTY_REWARDS.md

@@ -0,0 +1,30 @@
+# Loyalty and Rewards API
+
+All customer APIs are authenticated and derive the loyalty owner from the session.
+
+## Customer
+
+- `GET /api/v1/loyalty` — balance, debt, lifetime points, current tier, benefits, and next-tier progress.
+- `GET /api/v1/loyalty/history?page=&limit=` — paginated immutable ledger.
+- `GET /api/v1/loyalty/tiers`, `GET /api/v1/loyalty/rewards`.
+- `POST /api/v1/loyalty/redeem` — requires `Idempotency-Key` and reward ID.
+- `GET /api/v1/loyalty/vouchers` — owner-specific coupon entitlements.
+- `GET /api/v1/loyalty/referral`, `POST /api/v1/loyalty/referral/claim`.
+
+## Administration
+
+- Loyalty accounts and referral listing.
+- Tier, earn-rule, and reward listing/creation.
+- `POST /admin/loyalty/adjustments` requires `loyalty.points.adjust`, a non-zero integer delta, reason, and idempotency key.
+
+## Policy
+
+Purchase points are awarded only after authoritative PAID processing. Eligible value is discounted merchandise (`subtotal - discountTotal`), excluding shipping, tax, and duties. Money is divided by configured `amountUnit`, floored to whole units, then multiplied by configured points.
+
+Verified-review rewards require APPROVED and verified purchase. Referral rewards require the referred account's qualifying paid Order. Birthday events use `BIRTHDAY:user:year`; February 29 follows the actual calendar date.
+
+Ledger entries are never edited. Refund reversals append negative entries. If already-spent points prevent a complete debit, available points floor at zero and the remainder becomes explicit `pointsDebt`; later earnings repay debt first.
+
+Redemption locks the account/reward, validates limits, spends earliest-expiring allocations first, and creates at most one result per account/idempotency key. Coupon rewards reuse Phase 5 Coupon and issue an owner-specific entitlement.
+
+Expiry is configured per earn rule and reconciled in bounded daily batches. No direct balance/tier mutation API exists.