Describe stack states in API doc

Signed-off-by: Rashed Kamal <[email protected]>

Author: rashedkvm

docs/v3/source/includes/resources/stacks/_create.md.erb

@@ -12,6 +12,7 @@ curl "https://api.example.org/v3/stacks" \
   -d '{
     "name": "my-stack",
     "description": "Here is my stack!",
+    "state": "ACTIVE",
   }'
 ```
 
@@ -42,6 +43,7 @@ Name | Type | Description | Default
 **description** | _string_ | Description of the stack; must no longer than 250 characters | `null`
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
+**state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
 
 #### Permitted roles
  |

docs/v3/source/includes/resources/stacks/_header.md

@@ -12,3 +12,15 @@ An application will automatically use buildpacks associated with the application
 
 Stacks are not used for apps with a [Docker lifecycle](#docker-lifecycle).
 
+Operators control stack availability through state management. The following states determine how a stack can be used:
+
+*ACTIVE*: Default state. The stack is fully available for all operations.
+
+*DEPRECATED*: The stack is nearing end-of-life. It remains fully functional,
+but users should migrate to an ACTIVE stack.
+
+*RESTRICTED*: A transitional state typically applied before deprecation or disabling.
+New application creation is blocked; existing deployments continue to operate normally.
+
+*DISABLED*: The stack has reached end-of-life. New application creation and restaging are prohibited. 
+Running applications remain available.