docs: describe redemption code stacking and REDEMPTION_STACK_LIMIT

README.md

@@ -75,7 +75,7 @@ const { entitlementId } = await client.redeem({ code: voucherCode })
 
 Requires an OAuth access token with `entitlements:redeem` and a Worker that supports `POST /api/redeem`. Submission confirms redemption for the token's user, not the browser's logged-in account. No `userId` parameter is accepted. Keep client secrets and refresh tokens on the partner backend; the browser token provider should return only short-lived access tokens.
 
-Existing grants must obtain explicit consent for this new scope. Refreshing an old token does not add permissions. Active membership blocks redemption without consuming the voucher; a retry by the same user after successful redemption returns the original entitlement. API failures throw `PicGoCloudError` with `status` and `code` (for example `REDEMPTION_ACTIVE_MEMBERSHIP`, HTTP 409). The SDK does not automatically retry redemption. This method is new and is not included in the previously published `0.1.0` package.
+Existing grants must obtain explicit consent for this new scope. Refreshing an old token does not add permissions. Vouchers stack: remaining redemption time is consumed from the highest plan down, so a higher plan takes effect immediately and pauses lower ones, a lower plan is queued, and the same plan extends the time. An active subscription, admin grant or one-time purchase still blocks redemption (`REDEMPTION_ACTIVE_MEMBERSHIP`), and stacked time is capped at 3660 days (`REDEMPTION_STACK_LIMIT`); neither consumes the voucher. A retry by the same user after successful redemption returns the original entitlement. API failures throw `PicGoCloudError` with `status` and `code` (for example `REDEMPTION_ACTIVE_MEMBERSHIP`, HTTP 409). The SDK does not automatically retry redemption. This method is new and is not included in the previously published `0.1.0` package.
 
 ## Storage, membership and upload task status (OAuth)
 
@@ -85,7 +85,7 @@ const membership = await client.getEntitlements()   // entitlements:read
 const task = await client.getUploadStatus({ objectKey, uploadId }) // files:upload; uploadId only for multipart
 ```
 
-`getStorageUsage()` returns used/limit/remaining for bytes and media count plus the upload size and extension limits. `getEntitlements()` returns the plan, lifecycle phase, phase end time and an informational `redemption.eligible` hint; `redeem()` still decides on the server. `getUploadStatus()` reports whether the object of an upload started by the same user and OAuth client has arrived (`awaiting_object`, `object_uploaded` or `aborted`). These methods are new and not included in `0.1.0`.
+`getStorageUsage()` returns used/limit/remaining for bytes and media count plus the upload size and extension limits. `getEntitlements()` returns the plan, lifecycle phase, phase end time and an informational `redemption.eligible` hint. With stacked vouchers `currentPhaseEndsAt` is the end of the whole active period, and `plan` may change to a lower queued plan before then; `redeem()` still decides on the server. `getUploadStatus()` reports whether the object of an upload started by the same user and OAuth client has arrived (`awaiting_object`, `object_uploaded` or `aborted`). These methods are new and not included in `0.1.0`.
 ## Uploading files
 
 ```ts

README_ZH.md

@@ -74,7 +74,7 @@ const { entitlementId } = await client.redeem({ code: voucherCode })
 
 需要具备 `entitlements:redeem` 的 OAuth access token，以及支持 `POST /api/redeem` 的 Worker。提交即确认兑换，权益只发给 token 对应的用户，不依赖浏览器当前登录账号，不接受 `userId`。client secret 和 refresh token 必须留在合作方后端，浏览器 token provider 只取得短期 access token。
 
-老授权需要用户明确同意新增权限，刷新旧 token 不会自动获得权限。有生效会员时拒绝兑换且不消耗兑换码；同一用户重试已成功的兑换返回原 entitlement。失败抛出带 `status`、`code` 的 `PicGoCloudError`，例如 HTTP 409 / `REDEMPTION_ACTIVE_MEMBERSHIP`。SDK 不自动重试兑换。此方法是新增功能，已发布的 `0.1.0` 包尚不包含它。
+老授权需要用户明确同意新增权限，刷新旧 token 不会自动获得权限。兑换码可以叠加：剩余兑换时长按套餐等级由高到低依次消耗——更高套餐立即生效、低套餐顺延，更低套餐排在后面，同一套餐延长时间。存在生效中的订阅、管理员赠送或买断会员时仍拒绝兑换（`REDEMPTION_ACTIVE_MEMBERSHIP`），叠加总时长上限 3660 天（`REDEMPTION_STACK_LIMIT`），两种情况都不消耗兑换码。同一用户重试已成功的兑换返回原 entitlement。失败抛出带 `status`、`code` 的 `PicGoCloudError`，例如 HTTP 409 / `REDEMPTION_ACTIVE_MEMBERSHIP`。SDK 不自动重试兑换。此方法是新增功能，已发布的 `0.1.0` 包尚不包含它。
 
 ## 容量、会员与上传任务状态（OAuth）
 
@@ -84,7 +84,7 @@ const membership = await client.getEntitlements()   // entitlements:read
 const task = await client.getUploadStatus({ objectKey, uploadId }) // files:upload；仅分片上传需要 uploadId
 ```
 
-`getStorageUsage()` 返回容量字节数和文件数的已用/上限/剩余，以及单文件大小和扩展名限制。`getEntitlements()` 返回套餐、生命周期阶段、阶段结束时间，以及仅供参考的 `redemption.eligible`；能否兑换仍以 `redeem()` 的服务端结果为准。`getUploadStatus()` 报告同一用户、同一 OAuth 客户端发起的上传对象是否已到达（`awaiting_object`、`object_uploaded` 或 `aborted`）。这些方法是新增功能，`0.1.0` 尚不包含。
+`getStorageUsage()` 返回容量字节数和文件数的已用/上限/剩余，以及单文件大小和扩展名限制。`getEntitlements()` 返回套餐、生命周期阶段、阶段结束时间，以及仅供参考的 `redemption.eligible`。叠加兑换码时 `currentPhaseEndsAt` 是整个会员期的结束时间，在此之前 `plan` 可能切换为排在后面的较低套餐；能否兑换仍以 `redeem()` 的服务端结果为准。`getUploadStatus()` 报告同一用户、同一 OAuth 客户端发起的上传对象是否已到达（`awaiting_object`、`object_uploaded` 或 `aborted`）。这些方法是新增功能，`0.1.0` 尚不包含。
 ## 上传
 
 ```ts