fix(pay): preserve order note JSON, shared coupon burn, plate free VIP cashier

- Order_Repository: status note merges into JSON as status_note instead of wiping coupon/topic_pay meta
- Extract aksrt_burn_order_coupon / aksrt_coupon_usage_exists for content + topic
- Money plate follow (incl. VIP free) always opens multi-gateway cashier for 0-order ledger

inc/helpers/aksrt-coupon-order.php

@@ -0,0 +1,74 @@
+<?php
+/**
+ * Shared coupon burn helpers for cash content / topic orders.
+ *
+ * Idempotent via coupon_usage.order_number. Prefer note.coupon snapshot ids
+ * so burn still works after use_coupon increments used_count past limit.
+ *
+ * @package AKSRT
+ */
+
+defined('ABSPATH') || exit;
+
+if (!function_exists('aksrt_coupon_usage_exists')) {
+    /**
+     * Whether a coupon_usage row already exists for this order.
+     */
+    function aksrt_coupon_usage_exists(string $order_number): bool {
+        if ($order_number === '' || !class_exists('AKSRT_DB_Migrator')) {
+            return false;
+        }
+        global $wpdb;
+        $table = AKSRT_DB_Migrator::table('coupon_usage');
+        if ($table === '') {
+            return false;
+        }
+        $found = $wpdb->get_var($wpdb->prepare(
+            "SELECT id FROM {$table} WHERE order_number = %s LIMIT 1",
+            $order_number
+        ));
+        return !empty($found);
+    }
+}
+
+if (!function_exists('aksrt_burn_order_coupon')) {
+    /**
+     * Burn coupon for a paid cash order (use_coupon + log_usage).
+     *
+     * @param array<string,mixed> $meta Order note JSON (coupon_code / coupon / coupon_discount).
+     * @return bool True when a burn was attempted (or already burned).
+     */
+    function aksrt_burn_order_coupon(string $order_number, array $meta, int $buyer_id = 0): bool {
+        if ($order_number === '' || !class_exists('AKSRT_Coupon')) {
+            return false;
+        }
+        if (aksrt_coupon_usage_exists($order_number)) {
+            return true;
+        }
+
+        $coupon = is_array($meta['coupon'] ?? null) ? $meta['coupon'] : [];
+        $coupon_code = sanitize_text_field((string) ($coupon['code'] ?? $meta['coupon_code'] ?? ''));
+        $coupon_discount = (float) ($meta['coupon_discount'] ?? $meta['discount'] ?? ($coupon['discount'] ?? 0));
+        if ($coupon_code === '') {
+            return false;
+        }
+
+        $coupon_api = AKSRT_Coupon::get_instance();
+        $coupon_api->use_coupon($coupon_code);
+
+        // Prefer snapshot id: post-increment validate may fail on usage_limit edge.
+        $coupon_id = (int) ($coupon['id'] ?? 0);
+        if ($coupon_id <= 0) {
+            $validated = $coupon_api->validate($coupon_code, max(0.01, $coupon_discount), [
+                'user_id' => max(0, $buyer_id),
+            ]);
+            $coupon_id = (int) ($validated['coupon']['id'] ?? 0);
+        }
+
+        if ($coupon_id > 0) {
+            $coupon_api->log_usage($coupon_id, max(0, $buyer_id), $order_number, max(0.0, $coupon_discount));
+        }
+
+        return true;
+    }
+}