Add booking billable nights preview API and detail field

docs/API_REFERENCE.txt

@@ -1600,6 +1600,7 @@ BOOKING APIS
   What it does:
 
   - Returns booking snapshot details with stays, billing, ledger.
+  - Includes `billableNights` computed from booking timeline + booking billing policy.
 
   Request body:
 
@@ -1614,6 +1615,46 @@ BOOKING APIS
   - 404 Not Found
 
 
+- Preview booking billable nights API is this one:
+
+  POST /properties/{propertyId}/bookings/{bookingId}/billable-nights
+
+  What it does:
+
+  - Returns billable nights for the booking based on billing policy.
+  - OPEN booking: request must include both expectedCheckInAt and expectedCheckOutAt.
+  - CHECKED_IN booking: request must include expectedCheckOutAt only.
+  - CHECKED_OUT / CANCELLED / NO_SHOW booking: request must not send expected dates; server uses saved booking timeline.
+
+  Request body (BookingBillableNightsRequest):
+
+  {
+    "expectedCheckInAt": "2026-02-05T12:00:00+05:30",
+    "expectedCheckOutAt": "2026-02-06T11:00:00+05:30"
+  }
+
+  Response body (BookingBillableNightsResponse):
+
+  {
+    "bookingId": "uuid",
+    "status": "CHECKED_IN",
+    "billableNights": 2
+  }
+
+  - Allowed roles: ADMIN, MANAGER, STAFF, HOUSEKEEPING, FINANCE
+
+  Error Codes
+
+  - 400 Bad Request
+      - Invalid timestamp format ("Invalid timestamp")
+      - Invalid range ("Invalid date range")
+      - Missing required expected date by status
+      - expected dates provided for closed booking
+  - 401 Unauthorized
+  - 403 Forbidden
+  - 404 Not Found
+
+
 - Booking stream API is this one:
 
   GET /properties/{propertyId}/bookings/{bookingId}/stream