feat: Implement return and refund functionality in commerce module

- Added return request handling in return.controller.js
- Implemented webhook handling for PayHere payments in webhook.controller.js
- Created models for coupon redemptions, invoices, orders, order items, payments, payment attempts, payment webhook events, refunds, return items, and return requests.
- Developed services for order management, payment processing, refunds, and returns.
- Introduced validation schemas for payment and return requests.
- Created migration scripts for new database tables related to orders, payments, refunds, and returns.
- Added unit tests for order state transitions and PayHere provider functionality.

Documentation/PHASE_7_ORDERS_PAYMENTS.md

@@ -0,0 +1,84 @@
+# ZUMRI Phase 7 Orders and Payments
+
+## Objective
+Convert checkout snapshots into durable orders and establish authoritative payment, invoice, refund, and return lifecycles without delivery or rewards.
+
+## Existing Components Reused
+Checkout snapshots, inventory reservations, pricing money helpers, coupons, ReferenceNumber, document infrastructure, audit queue, authentication, and permissions.
+
+## Order Architecture
+Order/payment/fulfillment states are independent. Commercial and address/shipping details are immutable snapshots.
+
+## Checkout Conversion
+The centralized transaction locks an owned READY checkout, verifies reservations, returns any existing order, copies items, and converts checkout/cart.
+
+## Order State Machine
+Explicit transition sets reject illegal terminal-state transitions and arbitrary status patches.
+
+## Order Snapshots
+Items retain product/variant IDs, reservation key, SKU, names, quantity, unit price, discount, total, currency, and limited metadata.
+
+## Payment Architecture
+Payments retain immutable attempts. Only server/provider reconciliation changes authoritative financial state.
+
+## Provider Adapters
+Generic payment logic delegates verification/parsing/initiation/refund/status behavior to provider modules.
+
+## PayHere
+Merchant secrets are environmental. Browser redirects are non-authoritative; the notify hash, reference, amount, and currency must validate.
+
+## Stripe
+An explicit disabled boundary is present. Integration awaits official SDK/configuration rather than accepting unverified callbacks.
+
+## Webhook Verification
+Invalid signatures, currencies, amounts, and references are rejected.
+
+## Webhook Idempotency
+Unique provider/event records and locked payment/order rows ensure duplicate success cannot repeat side effects.
+
+## Inventory Consumption
+Checkout reserves; confirmed online payment consumes. Failed payment does not consume. Unpaid cancellation releases.
+
+## Payment Reconciliation
+Webhook persistence supports reconciliation, but remote status polling is deferred until the enabled provider supplies a validated status API.
+
+## Business Credit
+Disabled pending an approved immutable credit-ledger/accounting policy; concurrent unsafe balance mutation was not introduced.
+
+## Invoice Architecture
+One invoice per order uses transaction-safe ReferenceNumber sequencing. The existing document worker remains the PDF integration point.
+
+## Refund Architecture
+Idempotent itemized requests validate remaining quantity and captured amount. Provider processing is separate from request approval.
+
+## Return/RMA Architecture
+Owner-scoped requests and explicit admin transitions track physical receipt/condition independently from refunds.
+
+## Exchange Boundary
+EXCHANGE is recorded as resolution intent; no replacement order or fulfillment is created.
+
+## Coupon Redemption
+Redemption occurs once on confirmed payment while the coupon row is locked. Full-refund restoration is deferred by policy.
+
+## Verified Purchase Reviews
+Review creation derives verification only from an actual paid order containing the product.
+
+## Permissions
+Orders read/manage/cancel, payments read/manage/refund, invoices read, and returns read/manage were added.
+
+## Audit Events
+Order, payment creation, cancellation, refund request, return lifecycle, and admin operations reuse sanitized Phase 2 activity logging.
+
+## Database Changes
+Forward-only migration `20260909070000` creates eleven commerce tables with unique references/idempotency and lifecycle indexes.
+
+## Tests
+Unit tests cover order transitions, PayHere signature validation, forged notifications, secure return/refund inputs, and configurable return eligibility.
+
+## Remaining Known Issues
+Real PayHere, refunds, document generation, migration, webhook delivery, and MySQL concurrency were not exercised. Refund approval/provider completion APIs and reconciliation polling require provider policy/configuration.
+
+## Phase 8 Prerequisites
+Apply all migrations on restored staging, seed permissions, configure/validate PayHere sandbox, test concurrent duplicate webhooks, final-stock payment consumption, coupon quotas, invoice jobs, refund callbacks, and return restocking.
+
+Module 16 AI Customer Support Chatbot is intentionally excluded and planned as a separate service.